<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - interpolation_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2012  Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License   See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_INTERPOlATION_ABSTRACT_
<font color='#0000FF'>#ifdef</font> DLIB_INTERPOlATION_ABSTRACT_ 

<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../pixel.h.html'>../pixel.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../image_processing/full_object_detection_abstract.h.html'>../image_processing/full_object_detection_abstract.h</a>"

<font color='#0000FF'>namespace</font> dlib
<b>{</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='interpolate_nearest_neighbor'></a>interpolate_nearest_neighbor</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object is a tool for performing nearest neighbor interpolation
                on an image.  
        !*/</font>

    <font color='#0000FF'>public</font>:

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> image_type, 
            <font color='#0000FF'>typename</font> pixel_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>bool</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type<font color='#5555FF'>&amp;</font> img,
            <font color='#0000FF'>const</font> dlib::point<font color='#5555FF'>&amp;</font> p,
            pixel_type<font color='#5555FF'>&amp;</font> result
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            requires
                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
                - pixel_traits&lt;typename image_type::type&gt;::has_alpha == false
                - pixel_traits&lt;pixel_type&gt; is defined
            ensures
                - if (p is located inside img) then
                    - #result == img[p.y()][p.x()]
                      (This assignment is done using assign_pixel(#result, img[p.y()][p.x()]), 
                      therefore any necessary color space conversion will be performed)
                    - returns true
                - else
                    - returns false
        !*/</font>

    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='interpolate_bilinear'></a>interpolate_bilinear</b>
    <b>{</b>

        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object is a tool for performing bilinear interpolation
                on an image.  This is performed by looking at the 4 pixels
                nearest to a point and deriving an interpolated value from them.
        !*/</font>

    <font color='#0000FF'>public</font>:

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T, 
            <font color='#0000FF'>typename</font> image_type,
            <font color='#0000FF'>typename</font> pixel_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>bool</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type<font color='#5555FF'>&amp;</font> img,
            <font color='#0000FF'>const</font> dlib::vector<font color='#5555FF'>&lt;</font>T,<font color='#979000'>2</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> p,
            pixel_type<font color='#5555FF'>&amp;</font> result
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            requires
                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
                - pixel_traits&lt;typename image_type::type&gt;::has_alpha == false
                - pixel_traits&lt;pixel_type&gt; is defined
            ensures
                - if (there is an interpolatable image location at point p in img) then
                    - #result == the interpolated pixel value from img at point p.
                    - assign_pixel() will be used to write to #result, therefore any
                      necessary color space conversion will be performed.
                    - returns true
                    - if img contains RGB pixels then the interpolation will be in color.
                      Otherwise, the interpolation will be performed in a grayscale mode.
                - else
                    - returns false
        !*/</font>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='interpolate_quadratic'></a>interpolate_quadratic</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object is a tool for performing quadratic interpolation
                on an image.  This is performed by looking at the 9 pixels
                nearest to a point and deriving an interpolated value from them.
        !*/</font>

    <font color='#0000FF'>public</font>:

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T, 
            <font color='#0000FF'>typename</font> image_type,
            <font color='#0000FF'>typename</font> pixel_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>bool</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type<font color='#5555FF'>&amp;</font> img,
            <font color='#0000FF'>const</font> dlib::vector<font color='#5555FF'>&lt;</font>T,<font color='#979000'>2</font><font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> p,
            pixel_type<font color='#5555FF'>&amp;</font> result
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            requires
                - image_type == is an implementation of array2d/array2d_kernel_abstract.h
                - pixel_traits&lt;typename image_type::type&gt;::has_alpha == false
                - pixel_traits&lt;pixel_type&gt; is defined
            ensures
                - if (there is an interpolatable image location at point p in img) then
                    - #result == the interpolated pixel value from img at point p
                    - assign_pixel() will be used to write to #result, therefore any
                      necessary color space conversion will be performed.
                    - returns true
                    - if img contains RGB pixels then the interpolation will be in color.
                      Otherwise, the interpolation will be performed in a grayscale mode.
                - else
                    - returns false
        !*/</font>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='black_background'></a>black_background</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This is a function object which simply sets a pixel 
                to have a black value.
        !*/</font>

    <font color='#0000FF'>public</font>:
        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> pixel_type<font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font> pixel_type<font color='#5555FF'>&amp;</font> p<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#BB00BB'>assign_pixel</font><font face='Lucida Console'>(</font>p, <font color='#979000'>0</font><font face='Lucida Console'>)</font>; <b>}</b>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='white_background'></a>white_background</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This is a function object which simply sets a pixel 
                to have a white value.
        !*/</font>

    <font color='#0000FF'>public</font>:
        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> pixel_type<font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font> pixel_type<font color='#5555FF'>&amp;</font> p<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#BB00BB'>assign_pixel</font><font face='Lucida Console'>(</font>p, <font color='#979000'>255</font><font face='Lucida Console'>)</font>; <b>}</b>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>class</font> <b><a name='no_background'></a>no_background</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This is a function object which does nothing.  It is useful
                when used with the transform_image() routine defined below
                if no modification of uninterpolated output pixels is desired.
        !*/</font>
    <font color='#0000FF'>public</font>:
        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> pixel_type<font color='#5555FF'>&gt;</font>
        <font color='#0000FF'><u>void</u></font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font> pixel_type<font color='#5555FF'>&amp;</font> <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <b>}</b>
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> interpolation_type,
        <font color='#0000FF'>typename</font> point_mapping_type,
        <font color='#0000FF'>typename</font> background_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='transform_image'></a>transform_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp,
        <font color='#0000FF'>const</font> point_mapping_type<font color='#5555FF'>&amp;</font> map_point,
        <font color='#0000FF'>const</font> background_type<font color='#5555FF'>&amp;</font> set_background,
        <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> area
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - map_point should be a function which takes dlib::vector&lt;T,2&gt; objects and
              returns dlib::vector&lt;T,2&gt; objects.  An example is point_transform_affine.
            - set_background should be a function which can take a single argument of
              type image_type2::type.  Examples are black_background, white_background,
              and no_background.
            - get_rect(out_img).contains(area) == true
            - is_same_object(in_img, out_img) == false
        ensures
            - The map_point function defines a mapping from pixels in out_img to pixels
              in in_img.  transform_image() uses this mapping, along with the supplied
              interpolation routine interp, to fill the region of out_img defined by
              area with an interpolated copy of in_img.  
            - This function does not change the size of out_img.
            - Only pixels inside the region defined by area in out_img are modified.
            - For all locations r and c such that area.contains(c,r) but have no corresponding 
              locations in in_img:
                - set_background(out_img[r][c]) is invoked
                  (i.e. some parts of out_img might correspond to areas outside in_img and
                  therefore can't supply interpolated values.  In these cases, these
                  pixels can be assigned a value by the supplied set_background() routine)
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> interpolation_type,
        <font color='#0000FF'>typename</font> point_mapping_type,
        <font color='#0000FF'>typename</font> background_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='transform_image'></a>transform_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp,
        <font color='#0000FF'>const</font> point_mapping_type<font color='#5555FF'>&amp;</font> map_point,
        <font color='#0000FF'>const</font> background_type<font color='#5555FF'>&amp;</font> set_background
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - map_point should be a function which takes dlib::vector&lt;T,2&gt; objects and
              returns dlib::vector&lt;T,2&gt; objects.  An example is point_transform_affine.
            - set_background should be a function which can take a single argument of
              type image_type2::type.  Examples are black_background, white_background,
              and no_background.
            - is_same_object(in_img, out_img) == false
        ensures
            - performs: 
              transform_image(in_img, out_img, interp, map_point, set_background, get_rect(out_img));
              (i.e. runs transform_image() on the entire out_img)
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> interpolation_type,
        <font color='#0000FF'>typename</font> point_mapping_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='transform_image'></a>transform_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp,
        <font color='#0000FF'>const</font> point_mapping_type<font color='#5555FF'>&amp;</font> map_point
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - map_point should be a function which takes dlib::vector&lt;T,2&gt; objects and
              returns dlib::vector&lt;T,2&gt; objects.  An example is point_transform_affine.
            - is_same_object(in_img, out_img) == false
        ensures
            - performs: 
              transform_image(in_img, out_img, interp, map_point, black_background(), get_rect(out_img));
              (i.e. runs transform_image() on the entire out_img and sets non-interpolated
              pixels to black)
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> interpolation_type
        <font color='#5555FF'>&gt;</font>
    point_transform_affine <b><a name='rotate_image'></a>rotate_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'><u>double</u></font> angle,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img == a copy of in_img which has been rotated angle radians counter clockwise.
              The rotation is performed with respect to the center of the image.  
            - Parts of #out_img which have no corresponding locations in in_img are set to black.
            - uses the supplied interpolation routine interp to perform the necessary
              pixel interpolation.
            - returns a transformation object that maps points in in_img into their corresponding 
              location in #out_img.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>

    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    point_transform_affine <b><a name='rotate_image'></a>rotate_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'><u>double</u></font> angle
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type1::type&gt;::has_alpha == false
            - pixel_traits&lt;typename image_type2::type&gt; is defined
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img == a copy of in_img which has been rotated angle radians counter clockwise.
              The rotation is performed with respect to the center of the image.  
            - Parts of #out_img which have no corresponding locations in in_img are set to black.
            - uses the interpolate_quadratic object to perform the necessary pixel interpolation.
            - returns a transformation object that maps points in in_img into their corresponding 
              location in #out_img.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> interpolation_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='resize_image'></a>resize_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img == A copy of in_img which has been stretched so that it 
              fits exactly into out_img.   
            - The size of out_img is not modified.  I.e. 
                - #out_img.nr() == out_img.nr()
                - #out_img.nc() == out_img.nc()
            - uses the supplied interpolation routine interp to perform the necessary
              pixel interpolation.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>

    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='resize_image'></a>resize_image</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type1::type&gt;::has_alpha == false
            - pixel_traits&lt;typename image_type2::type&gt; is defined
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img == A copy of in_img which has been stretched so that it 
              fits exactly into out_img.   
            - The size of out_img is not modified.  I.e. 
                - #out_img.nr() == out_img.nr()
                - #out_img.nc() == out_img.nc()
            - Uses the bilinear interpolation to perform the necessary pixel interpolation.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    point_transform_affine <b><a name='flip_image_left_right'></a>flip_image_left_right</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type1::type&gt; is defined
            - pixel_traits&lt;typename image_type2::type&gt; is defined
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img.nr() == in_img.nr()
            - #out_img.nc() == in_img.nc()
            - #out_img == a copy of in_img which has been flipped from left to right.  
              (i.e. it is flipped as if viewed though a mirror)
            - returns a transformation object that maps points in in_img into their
              corresponding location in #out_img.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type,
        <font color='#0000FF'>typename</font> T
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='add_image_left_right_flips'></a>add_image_left_right_flips</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - T == rectangle or full_object_detection
            - images.size() == objects.size()
        ensures
            - This function computes all the left/right flips of the contents of images and
              then appends them onto the end of the images array.  It also finds the
              left/right flips of the rectangles in objects and similarly appends them into
              objects.  That is, we assume objects[i] is the set of bounding boxes in
              images[i] and we flip the bounding boxes so that they still bound the same
              objects in the new flipped images.
            - #images.size() == images.size()*2
            - #objects.size() == objects.size()*2
            - All the original elements of images and objects are left unmodified.  That
              is, this function only appends new elements to each of these containers.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type,
        <font color='#0000FF'>typename</font> T,
        <font color='#0000FF'>typename</font> U
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='add_image_left_right_flips'></a>add_image_left_right_flips</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects2
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - images.size() == objects2.size()
            - T == rectangle or full_object_detection
            - U == rectangle or full_object_detection
        ensures
            - This function computes all the left/right flips of the contents of images and
              then appends them onto the end of the images array.  It also finds the
              left/right flips of the rectangles in objects and objects2 and similarly
              appends them into objects and objects2 respectively.  That is, we assume
              objects[i] is the set of bounding boxes in images[i] and we flip the bounding
              boxes so that they still bound the same objects in the new flipped images.
              We similarly flip the boxes in objects2.
            - #images.size()   == images.size()*2
            - #objects.size()  == objects.size()*2
            - #objects2.size() == objects2.size()*2
            - All the original elements of images, objects, and objects2 are left unmodified.
              That is, this function only appends new elements to each of these containers.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type, 
        <font color='#0000FF'>typename</font> EXP, 
        <font color='#0000FF'>typename</font> T, 
        <font color='#0000FF'>typename</font> U
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='add_image_rotations'></a>add_image_rotations</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>EXP<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> angles,
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects2
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - is_vector(angles) == true
            - angles.size() &gt; 0
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - images.size() == objects2.size()
            - T == rectangle or full_object_detection
            - U == rectangle or full_object_detection
        ensures
            - This function computes angles.size() different rotations of all the given
              images and then replaces the contents of images with those rotations of the
              input dataset.  We will also adjust the rectangles inside objects and
              objects2 so that they still bound the same objects in the new rotated images.
              That is, we assume objects[i] and objects2[i] are bounding boxes for things
              in images[i].  So we will adjust the positions of the boxes in objects and
              objects2 accordingly.
            - The elements of angles are interpreted as angles in radians and we will
              rotate the images around their center using the values in angles.  Moreover,
              the rotation is done counter clockwise.
            - #images.size()   == images.size()*angles.size()
            - #objects.size()  == objects.size()*angles.size()
            - #objects2.size() == objects2.size()*angles.size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type, 
        <font color='#0000FF'>typename</font> EXP,
        <font color='#0000FF'>typename</font> T
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='add_image_rotations'></a>add_image_rotations</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>EXP<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> angles,
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - is_vector(angles) == true
            - angles.size() &gt; 0
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - T == rectangle or full_object_detection
        ensures
            - This function is identical to the add_image_rotations() define above except
              that it doesn't have objects2 as an argument.  
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='flip_image_dataset_left_right'></a>flip_image_dataset_left_right</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images, 
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
        ensures
            - This function replaces each image in images with the left/right flipped
              version of the image.  Therefore, #images[i] will contain the left/right
              flipped version of images[i].  It also flips all the rectangles in objects so
              that they still bound the same visual objects in each image.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='flip_image_dataset_left_right'></a>flip_image_dataset_left_right</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images, 
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects2
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - images.size() == objects2.size()
        ensures
            - This function replaces each image in images with the left/right flipped
              version of the image.  Therefore, #images[i] will contain the left/right
              flipped version of images[i].  It also flips all the rectangles in objects
              and objects2 so that they still bound the same visual objects in each image.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - #objects2.size() == objects2.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
            - for all valid i:
                #objects2[i].size() == objects2[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> pyramid_type,
        <font color='#0000FF'>typename</font> image_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='upsample_image_dataset'></a>upsample_image_dataset</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
        ensures
            - This function replaces each image in images with an upsampled version of that
              image.  Each image is upsampled using pyramid_up() and the given
              pyramid_type.  Therefore, #images[i] will contain the larger upsampled
              version of images[i].  It also adjusts all the rectangles in objects so that
              they still bound the same visual objects in each image.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> pyramid_type,
        <font color='#0000FF'>typename</font> image_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='upsample_image_dataset'></a>upsample_image_dataset</b> <font face='Lucida Console'>(</font>
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects2 
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - images.size() == objects2.size()
        ensures
            - This function replaces each image in images with an upsampled version of that
              image.  Each image is upsampled using pyramid_up() and the given
              pyramid_type.  Therefore, #images[i] will contain the larger upsampled
              version of images[i].  It also adjusts all the rectangles in objects and
              objects2 so that they still bound the same visual objects in each image.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - #objects2.size() == objects2.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
            - for all valid i:
                #objects2[i].size() == objects2[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> image_type<font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='rotate_image_dataset'></a>rotate_image_dataset</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'><u>double</u></font> angle,
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
        ensures
            - This function replaces each image in images with a rotated version of that
              image.  In particular, each image is rotated using
              rotate_image(original,rotated,angle).  Therefore, the images are rotated
              angle radians counter clockwise around their centers. That is, #images[i]
              will contain the rotated version of images[i].  It also adjusts all
              the rectangles in objects so that they still bound the same visual objects in
              each image.
            - All the rectangles will still have the same sizes and aspect ratios after
              rotation.  They will simply have had their positions adjusted so they still
              fall on the same objects.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> image_type<font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='rotate_image_dataset'></a>rotate_image_dataset</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'><u>double</u></font> angle,
        dlib::array<font color='#5555FF'>&lt;</font>image_type<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> images,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects,
        std::vector<font color='#5555FF'>&lt;</font>std::vector<font color='#5555FF'>&lt;</font>rectangle<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> objects2
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type::type&gt; is defined
            - images.size() == objects.size()
            - images.size() == objects2.size()
        ensures
            - This function replaces each image in images with a rotated version of that
              image.  In particular, each image is rotated using
              rotate_image(original,rotated,angle).  Therefore, the images are rotated
              angle radians counter clockwise around their centers. That is, #images[i]
              will contain the rotated version of images[i].  It also adjusts all
              the rectangles in objects and objects2 so that they still bound the same
              visual objects in each image.
            - All the rectangles will still have the same sizes and aspect ratios after
              rotation.  They will simply have had their positions adjusted so they still
              fall on the same objects.
            - #images.size() == image.size()
            - #objects.size() == objects.size()
            - #objects2.size() == objects2.size()
            - for all valid i:
                #objects[i].size() == objects[i].size()
            - for all valid i:
                #objects2[i].size() == objects2[i].size()
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='flip_image_up_down'></a>flip_image_up_down</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type1::type&gt; is defined
            - pixel_traits&lt;typename image_type2::type&gt; is defined
            - is_same_object(in_img, out_img) == false
        ensures
            - #out_img.nr() == in_img.nr()
            - #out_img.nc() == in_img.nc()
            - #out_img == a copy of in_img which has been flipped upside down.  
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> pyramid_type,
        <font color='#0000FF'>typename</font> interpolation_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='pyramid_up'></a>pyramid_up</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> pyramid_type<font color='#5555FF'>&amp;</font> pyr,
        <font color='#0000FF'>const</font> interpolation_type<font color='#5555FF'>&amp;</font> interp
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pyramid_type == a type compatible with the image pyramid objects defined 
              in dlib/image_transforms/image_pyramid_abstract.h
            - interpolation_type == interpolate_nearest_neighbor, interpolate_bilinear, 
              interpolate_quadratic, or a type with a compatible interface.
            - is_same_object(in_img, out_img) == false
        ensures
            - This function inverts the downsampling transformation performed by pyr().
              In particular, it attempts to make an image, out_img, which would result
              in in_img when downsampled with pyr().  
            - #out_img == An upsampled copy of in_img.  In particular, downsampling
              #out_img 1 time with pyr() should result in a final image which looks like
              in_img.
            - Uses the supplied interpolation routine interp to perform the necessary
              pixel interpolation.
            - Note that downsampling an image with pyr() and then upsampling it with 
              pyramid_up() will not necessarily result in a final image which is
              the same size as the original.  This is because the exact size of the
              original image cannot be determined based on the downsampled image.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2,
        <font color='#0000FF'>typename</font> pyramid_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='pyramid_up'></a>pyramid_up</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> in_img,
        image_type2<font color='#5555FF'>&amp;</font> out_img,
        <font color='#0000FF'>const</font> pyramid_type<font color='#5555FF'>&amp;</font> pyr
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pyramid_type == a type compatible with the image pyramid objects defined 
              in dlib/image_transforms/image_pyramid_abstract.h
            - is_same_object(in_img, out_img) == false
        ensures
            - performs: pyramid_up(in_img, out_img, pyr, interpolate_bilinear());
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type,
        <font color='#0000FF'>typename</font> pyramid_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='pyramid_up'></a>pyramid_up</b> <font face='Lucida Console'>(</font>
        image_type<font color='#5555FF'>&amp;</font> img,
        <font color='#0000FF'>const</font> pyramid_type<font color='#5555FF'>&amp;</font> pyr
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
            - pyramid_type == a type compatible with the image pyramid objects defined 
              in dlib/image_transforms/image_pyramid_abstract.h
        ensures
            - Performs an in-place version of pyramid_up() on the given image.  In
              particular, this function is equivalent to:
                pyramid_up(img, temp, pyr); 
                temp.swap(img);
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='pyramid_up'></a>pyramid_up</b> <font face='Lucida Console'>(</font>
        image_type<font color='#5555FF'>&amp;</font> img
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type == is an implementation of array2d/array2d_kernel_abstract.h
        ensures
            - performs: pyramid_up(img, pyramid_down&lt;2&gt;());
              (i.e. it upsamples the given image and doubles it in size.)
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>struct</font> <b><a name='chip_dims'></a>chip_dims</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This is a simple tool for passing in a pair of row and column values to the
                chip_details constructor.
        !*/</font>

        <b><a name='chip_dims'></a>chip_dims</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> rows_,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cols_
        <font face='Lucida Console'>)</font> : rows<font face='Lucida Console'>(</font>rows_<font face='Lucida Console'>)</font>, cols<font face='Lucida Console'>(</font>cols_<font face='Lucida Console'>)</font> <b>{</b> <b>}</b>

        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> rows;
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cols;
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>struct</font> <b><a name='chip_details'></a>chip_details</b>
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object describes where an image chip is to be extracted from within
                another image.  In particular, it specifies that the image chip is
                contained within the rectangle this-&gt;rect and that prior to extraction the
                image should be rotated counter-clockwise by this-&gt;angle radians.  Finally,
                the extracted chip should have this-&gt;rows rows and this-&gt;cols columns in it
                regardless of the shape of this-&gt;rect.

        !*/</font>

        <b><a name='chip_details'></a>chip_details</b><font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>; 
        <font color='#009900'>/*!
            ensures
                - #rect.is_empty() == true
                - #size() == 0
                - #angle == 0
                - #rows == 0
                - #cols == 0
        !*/</font>

        <b><a name='chip_details'></a>chip_details</b><font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect_, 
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> size_
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #rect == rect_
                - #size() == size_
                - #angle == 0
                - #rows and #cols is set such that the total size of the chip is as close
                  to size_ as possible but still matches the aspect ratio of rect_.
                - As long as size_ and the aspect ratio of of rect_ stays constant then
                  #rows and #cols will always have the same values.  This means that, for
                  example, if you want all your chips to have the same dimensions then
                  ensure that size_ is always the same and also that rect_ always has the
                  same aspect ratio.  Otherwise the calculated values of #rows and #cols
                  may be different for different chips.  Alternatively, you can use the
                  chip_details constructor below that lets you specify the exact values for
                  rows and cols.
        !*/</font>

        <b><a name='chip_details'></a>chip_details</b><font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect_, 
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> size_,
            <font color='#0000FF'><u>double</u></font> angle_
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #rect == rect_
                - #size() == size_
                - #angle == angle_
                - #rows and #cols is set such that the total size of the chip is as close
                  to size_ as possible but still matches the aspect ratio of rect_.
                - As long as size_ and the aspect ratio of of rect_ stays constant then
                  #rows and #cols will always have the same values.  This means that, for
                  example, if you want all your chips to have the same dimensions then
                  ensure that size_ is always the same and also that rect_ always has the
                  same aspect ratio.  Otherwise the calculated values of #rows and #cols
                  may be different for different chips.  Alternatively, you can use the
                  chip_details constructor below that lets you specify the exact values for
                  rows and cols.
        !*/</font>

        <b><a name='chip_details'></a>chip_details</b><font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect_, 
            <font color='#0000FF'>const</font> chip_dims<font color='#5555FF'>&amp;</font> dims
        <font face='Lucida Console'>)</font>; 
        <font color='#009900'>/*!
            ensures
                - #rect == rect_
                - #size() == dims.rows*dims.cols 
                - #angle == 0
                - #rows == dims.rows
                - #cols == dims.cols
        !*/</font>

        <b><a name='chip_details'></a>chip_details</b><font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect_, 
            <font color='#0000FF'>const</font> chip_dims<font color='#5555FF'>&amp;</font> dims,
            <font color='#0000FF'><u>double</u></font> angle_
        <font face='Lucida Console'>)</font>; 
        <font color='#009900'>/*!
            ensures
                - #rect == rect_
                - #size() == dims.rows*dims.cols 
                - #angle == angle_
                - #rows == dims.rows
                - #cols == dims.cols
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='size'></a>size</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> rows<font color='#5555FF'>*</font>cols; <b>}</b>
        <font color='#009900'>/*!
            ensures
                - returns the number of pixels in this chip.  This is just rows*cols.
        !*/</font>

        rectangle rect;
        <font color='#0000FF'><u>double</u></font> angle;
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> rows; 
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cols;
    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='extract_image_chips'></a>extract_image_chips</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> img,
        <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>chip_details<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> chip_locations,
        dlib::array<font color='#5555FF'>&lt;</font>image_type2<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> chips
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        requires
            - image_type1 == is an implementation of array2d/array2d_kernel_abstract.h
            - image_type2 == is an implementation of array2d/array2d_kernel_abstract.h
            - pixel_traits&lt;typename image_type1::type&gt;::has_alpha == false
            - pixel_traits&lt;typename image_type2::type&gt; is defined
            - for all valid i: 
                - chip_locations[i].rect.is_empty() == false
                - chip_locations[i].size != 0
        ensures
            - This function extracts "chips" from an image.  That is, it takes a list of
              rectangular sub-windows (i.e. chips) within an image and extracts those
              sub-windows, storing each into its own image.  It also scales and rotates the
              image chips according to the instructions inside each chip_details object.
            - #chips == the extracted image chips
            - #chips.size() == chip_locations.size()
            - for all valid i:
                - #chips[i] == The image chip extracted from the position
                  chip_locations[i].rect in img.
                - #chips[i].nr() == chip_locations[i].rows
                - #chips[i].nc() == chip_locations[i].cols
                - The image will have been rotated counter-clockwise by
                  chip_locations[i].angle radians, around the center of
                  chip_locations[i].rect, before the chip was extracted. 
            - Any pixels in an image chip that go outside img are set to 0 (i.e. black).
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'>typename</font> image_type1,
        <font color='#0000FF'>typename</font> image_type2
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='extract_image_chip'></a>extract_image_chip</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> image_type1<font color='#5555FF'>&amp;</font> img,
        <font color='#0000FF'>const</font> chip_details<font color='#5555FF'>&amp;</font> chip_location,
        image_type2<font color='#5555FF'>&amp;</font> chip
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        ensures
            - This function simply calls extract_image_chips() with a single chip location
              and stores the single output chip into #chip.
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<b>}</b>

<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_INTERPOlATION_ABSTRACT_
</font>

</pre></body></html>